# Snow CLI User Guide - Async Task Management

The async task feature allows you to run time-consuming AI tasks in the background while continuing to use your terminal for other work. Tasks run in independent processes and won't block your operations.

## What Are Async Tasks

Async tasks are suitable for the following scenarios:

- Long-running code analysis and refactoring
- Batch file processing and conversion
- Generating detailed project documentation
- Executing complex multi-step operations

You can create tasks to run in the background, check results later, or approve sensitive operations when needed.

## Creating Background Tasks

Use the `--task` parameter in the terminal to create a background task:

```bash
snow --task "Analyze project code and generate architecture documentation"
```

After execution, task information will be displayed and control returns immediately:

```text
Task created: abc-123-def-456
Title: Analyze project code and generate architecture documentation
Use "snow --task-list" to view task status
```

The task will run in an independent background process, allowing you to continue using the terminal for other work.

## Opening Task Manager

There are two ways to open the task manager to view and manage background tasks:

### 1. Command Line Launch

```bash
snow --task-list
```

### 2. Welcome Menu

After launching Snow CLI, select the "Task Manager" option from the main menu.

## Viewing Task List

After entering the task manager, you'll see a list of all tasks. Each task displays:

- Status icon and color
- Task title (first 50 characters of the prompt)
- Last update time
- Message count

### Task Status

- `○` Yellow - Pending: Task created but not yet started
- `◐` Cyan - Running: Task is executing in the background
- `⏸` Magenta - Paused: Sensitive command detected, waiting for your approval
- `●` Green - Completed: Task executed successfully
- `✗` Red - Failed: Task execution error

## Operation Shortcuts

### In Task List

- `↑` `↓` - Navigate up/down
- `Space` - Mark/unmark task (for batch deletion)
- `Enter` - View task details
- `D` - Delete task
  - Single delete: Select and press `D`, press `D` again to confirm
  - Batch delete: Mark multiple tasks with `Space`, press `D`, press `D` again to confirm
- `R` - Refresh task list
- `Esc` - Exit task manager

### In Task Details

- `C` - Convert task to session for continued conversation
  - Press `C` once to show prompt
  - Press `C` again to confirm conversion
- `A` - Approve sensitive command execution (only available when paused)
- `R` - Reject sensitive command (only available when paused)
- `Esc` - Return to task list

## Approving Sensitive Commands

When a background task needs to execute dangerous operations (like deleting files, resetting code, etc.), it will automatically pause and wait for your approval.

### Approval Steps

1. See the pause icon `⏸` and magenta status in the task list
2. Press `Enter` to view task details
3. Check the specific command shown in the yellow warning box
4. Choose based on the situation:
   - Press `A` - Approve execution, task continues running
   - Press `R` - Reject execution

### Rejecting Commands with Reason

1. Press `R` on the paused task details page
2. Enter input mode, cursor displays as █
3. Enter rejection reason, e.g., "Insufficient permissions, please execute manually"
4. Press `Enter` to submit
5. Press `Esc` to cancel input

After rejection, the AI will receive your reason and adjust subsequent operations accordingly.

### Configuring Sensitive Commands

You can customize which commands require approval. See [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md).

## Converting Tasks to Sessions

Completed tasks can be converted to regular sessions, allowing you to continue conversing with the AI, ask for more details, or request modifications.

### Conversion Method

1. Select a task in the task list
2. Press `Enter` to view details
3. Press `C` key (confirmation prompt appears)
4. Press `C` again to confirm
5. Automatically jump to chat interface

### Notes

- Original task will be deleted after conversion
- All message history will be preserved in the new session
- Incomplete tasks can also be converted, but with a warning prompt
- Conversion operation cannot be undone

## Viewing Task Logs

Each task has an independent log file that records detailed execution process.

### Log Location

Task creation displays the log path:

```text
Task abc-123-def-456 started in background (PID: 12345)
Logs: /Users/username/.snow/task-logs/abc-123-def-456.log
```

### Viewing Logs

Use any text editor or command-line tool:

```bash
# View logs in real-time
tail -f ~/.snow/task-logs/abc-123-def-456.log

# View complete log
cat ~/.snow/task-logs/abc-123-def-456.log
```

Logs contain:

- Task start and end times
- All output information
- Error information and stack traces
- Execution process tracking

## Usage Scenarios

### Scenario 1: Long-Running Code Analysis

```bash
# Create background task
snow --task "Comprehensively analyze project code, generate architecture documentation and optimization suggestions"

# Continue other work
cd other-project
git pull

# Check results later
snow --task-list
```

### Scenario 2: Batch File Refactoring

```bash
# Execute refactoring in background
snow --task "Refactor all components in src/components, use TS strict mode uniformly"

# Task will pause when detecting file deletion operations
# Open task manager to approve
```

### Scenario 3: Generate Reports and Continue Discussion

```bash
# Create analysis task
snow --task "Analyze Git commits from the last week, generate code quality report"

# After task completes
snow --task-list
# Select task → Enter → C → C to convert to session
# Then continue asking: "Which parts should be prioritized for optimization?"
```

## FAQ

### Q: Task status stuck at "Running"?

A: The task might be executing time-consuming operations. You can:

- Check logs to understand current progress
- Wait longer
- If confirmed stuck, delete the task and recreate it

### Q: What to do if task failed?

A:

1. Check logs to find the error cause
2. Verify if the prompt is reasonable
3. Confirm if system resources are sufficient
4. Modify and recreate the task

### Q: How to delete multiple tasks?

A:

1. Use `Space` key to mark tasks to delete (shows marked count)
2. Press `D` key
3. Press `D` again to confirm batch deletion

### Q: Sensitive command not pausing?

A: Check if the command pattern has been added in [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md).

### Q: How many tasks can run simultaneously?

A: There's no theoretical limit, but each task consumes system resources. It's recommended to control the number based on machine performance.

## Practical Tips

1. **Clear Task Goals** - Provide clear and specific prompts when creating tasks, let the AI know what to do
2. **Regular Cleanup** - Delete unneeded completed tasks to keep the list clean
3. **Use Marking** - Batch mark unwanted tasks for one-time deletion
4. **Check Logs** - For long-running tasks, check logs to understand progress
5. **Convert to Session** - After important tasks complete, convert to session for easy follow-up queries and modifications

## Related Documentation

- [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md) - Configure commands requiring approval
- [Headless Mode](./12.Headless%20Mode.md) - Another non-interactive execution mode
- [Command Panel Guide](./09.0.Command%20Panel%20Guide.md) - Learn more management commands